emoji-regex

What is emoji-regex?

The emoji-regex npm package provides a regular expression to match all Emoji-only symbols as per the Unicode Standard. This package is useful for processing text that contains emojis, allowing developers to identify, validate, or manipulate emojis within strings.

What are emoji-regex's main functionalities?

Matching emojis in a string

This code sample demonstrates how to use emoji-regex to find all emojis in a given string. The regex is executed against a string containing emojis, and it will match each emoji character or sequence.

/(emojiRegex())/g.exec('I ❤️ emoji!')

Replacing emojis in a string

This code sample shows how to replace all emojis in a string with a specific word or character. In this case, every emoji in the string is replaced with the word 'emoji'.

'I ❤️ emoji!'.replace(emojiRegex(), 'emoji')

Counting emojis in a string

This code sample is used to count the number of emojis in a string. The match function returns an array of all emojis found, and the length property of the array indicates the total number of emojis.

'👍👍🏿'.match(emojiRegex()).length

Other packages similar to emoji-regex

emojione

Emojione is a package that provides emoji conversion and detection. It includes functionalities to convert unicode emojis to shortnames, images, and vice versa. It is more feature-rich compared to emoji-regex, which focuses solely on regex matching.

node-emoji

Node-emoji is a package that allows for simple emoji handling and conversion in Node.js. It can convert emoji names to unicode and unicode to names, similar to emojione but with a simpler API. Unlike emoji-regex, it does not provide a regex pattern for matching emojis.

emoji-aware

Emoji-aware is a package that splits strings into arrays of Unicode emoji and text. It is useful for separating emojis from other text, but it does not provide regex functionality like emoji-regex.

README

emoji-regex

emoji-regex offers a regular expression to match all emoji symbols and sequences (including textual representations of emoji) as per the Unicode Standard.

This repository contains a script that generates this regular expression based on Unicode data. Because of this, the regular expression can easily be updated whenever new emoji are added to the Unicode standard.

Installation

Via npm:

npm install emoji-regex

In Node.js:

const emojiRegex = require('emoji-regex/RGI_Emoji.js');
// Note: because the regular expression has the global flag set, this module
// exports a function that returns the regex rather than exporting the regular
// expression itself, to make it impossible to (accidentally) mutate the
// original regular expression.

const text = `
\u{231A}: ⌚ default emoji presentation character (Emoji_Presentation)
\u{2194}\u{FE0F}: ↔️ default text presentation character rendered as emoji
\u{1F469}: 👩 emoji modifier base (Emoji_Modifier_Base)
\u{1F469}\u{1F3FF}: 👩🏿 emoji modifier base followed by a modifier
`;

const regex = emojiRegex();
let match;
while (match = regex.exec(text)) {
  const emoji = match[0];
  console.log(`Matched sequence ${ emoji } — code points: ${ [...emoji].length }`);
}

Console output:

Matched sequence ⌚ — code points: 1
Matched sequence ⌚ — code points: 1
Matched sequence ↔️ — code points: 2
Matched sequence ↔️ — code points: 2
Matched sequence 👩 — code points: 1
Matched sequence 👩 — code points: 1
Matched sequence 👩🏿 — code points: 2
Matched sequence 👩🏿 — code points: 2

Regular expression flavors

The package comes with three distinct regular expressions:

// This is the recommended regular expression to use. It matches all
// emoji recommended for general interchange, as defined via the
// `RGI_Emoji` property in the Unicode Standard.
// https://unicode.org/reports/tr51/#def_rgi_set
// When in doubt, use this!
const emojiRegexRGI = require('emoji-regex/RGI_Emoji.js');

// This is the old regular expression, prior to `RGI_Emoji` being
// standardized. In addition to all `RGI_Emoji` sequences, it matches
// some emoji you probably don’t want to match (such as emoji component
// symbols that are not meant to be used separately).
const emojiRegex = require('emoji-regex/index.js');

// This regular expression matches even more emoji than the previous
// one, including emoji that render as text instead of icons (i.e.
// emoji that are not `Emoji_Presentation` symbols and that aren’t
// forced to render as emoji by a variation selector).
const emojiRegexText = require('emoji-regex/text.js');

Additionally, in environments which support ES2015 Unicode escapes, you may require ES2015-style versions of the regexes:

const emojiRegexRGI = require('emoji-regex/es2015/RGI_Emoji.js');
const emojiRegex = require('emoji-regex/es2015/index.js');
const emojiRegexText = require('emoji-regex/es2015/text.js');

For maintainers

How to update emoji-regex after new Unicode Standard releases

1. Update the Unicode data dependency in package.json by running the following commands:

   # Example: updating from Unicode v12 to Unicode v13.
   npm uninstall @unicode/unicode-12.0.0
   npm install @unicode/unicode-13.0.0 --save-dev
   

2. Generate the new output:

   npm run build
   

3. Verify that tests still pass:

   npm test
   

4. Send a pull request with the changes, and get it reviewed & merged.

5. On the main branch, bump the emoji-regex version number in package.json:

   npm version patch -m 'Release v%s'
   

   Instead of patch, use minor or major as needed.

   Note that this produces a Git commit + tag.

6. Push the release commit and tag:

   git push
   

   Our CI then automatically publishes the new release to npm.

Author

Mathias Bynens

License

emoji-regex is available under the MIT license.